bundler: return the module.exports export from require() of an ES module - #42092

Review of this PR raised seven concerns. Four are addressed: a require() result that is only feature-tested (const E = require("./events.mjs"); typeof E) printed var E = (init_events(), {}), because the unused-namespace pass did not know the result is the export (fixed, with cjs/require_esm_module_exports_export_tree_shaken_uses), and the docs named every browser polyfill where only 15 export the name (narrowed), and a --format=cjs bundle whose entry point exports the name still gave an external require() the namespace copy (fixed, see the --format=cjs paragraph below), and export * from "events" in a user module carried the polyfill's module.exports export into that module (fixed, see the export * paragraph below). Three are kept as choices: each require() call reads the export live (next paragraph), a null or undefined export falls back to the namespace copy (the http polyfill cycle below needs it, and bun run does the same), and require() of the 15 polyfills changes shape on purpose (no __esModule, no .default, which is the fix for #19808).

export * and the polyfills: a Node.js builtin has no export named module.exports (checked on Node v26.3.0 and bun run: "module.exports" in ns is false for node:events and node:path). A polyfill declares one to name its own require() value, and an export * from "events" in a user module re-exported it. require() of that user module then returned the EventEmitter class and lost the module's other exports. The linker now skips that name when it resolves an ES export * whose target is a polyfill, under the same condition that skips default (ExportStarContext::add_exports). The re-exporting module then has no such export, so require() of it, a --format=cjs entry point and the export clause of a --format=esm entry point all behave as on main. A lifted module.exports = require("events") file still forwards it, as it forwards default. The dev server lowers export * to a spread, which copies the key, so its require() asks which module declares the name (the exports and stars lists of the module registry) and does not follow export * into a node: module. export * between user modules still carries the name, as in Node. Tests: browser/NodePolyfillExportStar prints the same three lines as node and bun run, plus ..FormatCjsEntry, ..FormatEsmEntry and a dev-server case. Still different from Node: import * as ns from "events" lists a module.exports key on the polyfill's own namespace object.

A split require() (--splitting --target=bun) already honored the export at run time, so before this change one source gave right with --splitting and WRONG without.

Supersedes #41328 (built the assert and events polyfills as CommonJS) and #29993 (changed only the __toCommonJS helper). Both were narrower and are closed in favor of this PR. Their test programs are folded in as cjs/require_esm_module_exports_export_primitive, cjs/require_esm_module_exports_export_null, and the #19808 checks in browser/NodePolyfillRequireCallable.

Known difference from Node and bun run: each require() call reads the export live. Node and bun run keep the value from the first load. The two differ only when the module later reassigns the exported let binding. The live read is what lets a require() inside a cycle fall back to the namespace copy while a later call gets the export, with no second cache in the runtime helper.

The linker already assumed this interop: it keeps the module.exports export alive for require() targets (scanImportsAndExports.rs:294) and refuses to bind destructured names through it (LinkerContext.rs:4179).

Before and after, ev.cjs from the report built with --target=browser and run under node:

before: {"type":"object","EventEmitter":"function","default":"function"}
        THROWN: TypeError: Class extends value #<Object> is not a constructor or null
after:  {"type":"function","EventEmitter":"function","default":"undefined"}
        got 1

after is byte-identical to bun ev.cjs and node ev.cjs. The printed call is var EE = (init_events(), __toCommonJS(exports_events, 1));.

The #19808 program (const Assert = require("node:assert"); Assert.equal(1,1); Assert(true), --target=browser) throws TypeError: Assert.equal is not a function on bun 1.4.3 and runs here under bun and node. The #29985 program (require("./m.js") where m.js has export { b as "module.exports" }, b = 2) prints the namespace object on 1.4.3 and 2 here, as bun main.js and node do.

Node docs example (point.mjs with export { Point as "module.exports" }, required from a .cjs file), one line per check: node, bun run, and the new bundle all print function true 5 undefined / true false / star: function true / falsy: false / import(): true function default,midpoint,module.exports. bun 1.4.3's bundle throws at class Point3D extends Point. This covers export * propagation of the string name, a false value, identity across calls, no __esModule on the result, and an unchanged import() namespace.

Why the non-null fallback instead of Node's strict own-property rule: Node throws ERR_REQUIRE_CYCLE_MODULE for a require() inside the module's own evaluation, and bun run hands out namespace["module.exports"] ?? namespace. The prebuilt http polyfill has such a cycle (stream-http requires builtin-status-codes, whose node entry does require("http").STATUS_CODES). A strict exports_http["module.exports"] made import http from "node:http" throw at load. With the fallback the inner call sees the namespace copy, as it does today, and every later require("http") gets the stream-http object. An explicit null or undefined "module.exports" export therefore yields the namespace copy (Node yields the value). bun run does the same.

--format=cjs entry points: the bundle assigns module.exports = __toCommonJS(exports) before the body of the entry point, so that a cycle through an external module sees the exports object. When the entry point exports module.exports, the entry point tail now ends with module.exports = __toCommonJS(exports, 1), after the body ran (postProcessJSChunk.rs). require("./dist/lib.cjs") then returns what require("./lib.mjs") returns in Node and bun run, and what require() of the entry inside the bundle returns. On bun 1.4.3, class X extends require("./dist/lib.cjs") throws TypeError: The superclass is not a constructor. An export that is still null or undefined keeps the namespace copy, and an entry point without that export prints as before. Tests: cjs/require_esm_module_exports_export_format_cjs_entry, ..._format_cjs_entry_wrapped, ..._format_cjs_entry_null.

Sizes behind the Downsides numbers. One binary (this PR), bun build --target=browser --minify, with the prebuilt polyfills of main and of this PR swapped in:

With main's polyfills the linker binds the names read off require("path") to the exports and drops the namespace object and the __toCommonJS and __export helpers (#32557). The module.exports export turns that off, because the names are then properties of the exported value. import util from "node:util" grows because the default object lists 28 members, not 8. The __toCommonJS helper itself is 65 bytes longer minified and 182 unminified, and 88 to 112 bytes longer as bytecode (the four snapshot entries).

__importDefault(require("events")).default, __importStar(require("path")) and Babel's _interopRequireDefault(require("util")).default give the same values on bun 1.4.3, on this PR and in Node. A direct require("events").default is undefined here and in Node, and was the class on 1.4.3.

Polyfills changed: assert, console, events, http, https, net, path, punycode, querystring, string_decoder, sys, tty, url, util, zlib. Default exports that change value: assert (namespace of the CJS assert package -> the assert function), https and querystring (import-star namespace -> the package's module.exports object, same members), sys (namespace of util -> util's default object), util (8 members -> all 28 named exports, so require("util") keeps format and inspect). string_decoder keeps StringDecoder as its default and exports the { StringDecoder } package object as module.exports. buffer and crypto are unchanged: their wrapper is already object-shaped like Node's module.exports.

bundler_bytecode_portable's snapshot moves for the four --format=cjs ESM entries because the __toCommonJS helper text changed. The values were regenerated after each merge of main, from a clean test/ install, and CI checks them on every platform.

Not in this PR, checked on 1.4.3 and unchanged here: require("crypto").createHash is undefined because the prebuild resolves randombytes and friends to their node entries, which require("crypto") back into the polyfill mid-evaluation (#41524 builds the polyfills for the browser target). import { gzipSync } from "zlib" and import { toASCII } from "punycode" are still build errors because those polyfills export * from a CommonJS package (#41533). os, process, timers, domain and constants have only named exports, so their require() result was already Node-shaped apart from __esModule.

Other open PRs from this account that touch the same files: #41533 (also converts assert, while its util, zlib, punycode, console, process and Buffer changes are separate), #40072 (util default export and lint), #41524 and #41315 (build-fallbacks.ts, not touched here). REQUIRE_MODULE_EXPORTS_EXPORT is bit 30 of ImportRecordFlags, not the next free bit 19. On 2026-10-26, ten other open PRs add a flag at bit 19 (#42034, #41959, #40822, #46736, #46994, #45408, #42026, #41982, #41834, #43911), and open PRs also use bits 20 (#46216), 21 (#46681, #46579) and 22 (#45248, #35053). bitflags compiles two flags on one bit with no error and no warning, and each flag then reads as the other. Bit 30 is free on main and in every open PR (checked by reading src/ast/import_record.rs at the head of each open PR that touches it), so a merge that keeps both sides of the conflict in that file is correct.

Found while testing, handed off separately: bun build --format=iife with a CommonJS entry point defines require_entry and never calls it, so the entry does not run.

Suites run with the debug build: bundler_browser, bundler_cjs, bundler_cjs2esm, bundler_edgecase, bundler_dynamic_import_dce, bundler_splitting, bundler_minify, esbuild/default, esbuild/importstar, bake/dev/esm.